TransForm QuickLink in IFRAME
Description
Embed TransForm forms into your own applications.
Overview
Alpha TransForm is useful for capturing data through a form-like interface, often on mobile devices. There are times, though, when there is a need to use a custom web interface to create, view, or edit form instances where the TransForm UI is only a part of the interface. For example, an application may display information from a database where the TransForm form instance is only part of the data being used and displayed. When using the application, it may be necessary to display the form instance as a TransForm form, and maybe even allow editing of the data through the TransForm UI, all on the same screen and browser tab as the rest of the application.
As functionality to facilitate such use, TransForm QuickLink may be loaded into an <IFRAME> HTML element in another web application. An IFRAME element enables the embedding of another HTML page into the current one. The other application can use the framed QuickLink to view and edit form instances in a coordinated way. This is documentation about that use.
This documentation assumes familiarity with Alpha TransForm and the more direct use of QuickLink for accessing form instances through a web link provided to the user that is documented elsewhere, as well as familiarity with web technologies including HTML, JavaScript, and CSS.
Properties of QuickLink in an IFRAME
Using QuickLink to view and edit a form instance is similar to using the TransForm Filler once a particular form instance is chosen. Only the Form Details screens and Editors are shown. Unlike the Web Filler, there is no Forms List with QuickLink nor an Add a Blank Form list.
Unlike the Mobile Filler but similar to the Web Filler, QuickLink runs in a browser connected to the Internet. Once launched, it supports the viewing, editing, and saving of a single form instance.
When running in an IFRAME within another web application’s window, QuickLink gets setup instructions from that parent window as part of the IFRAME’s src attribute’s query string. It also can communicate back to that parent window through JavaScript’s postMessage functionality. This lets the parent window respond to changes in the QuickLink window, such as when the user has made edits to the accessed form instance, or when edits are saved back to the TransForm server.
QuickLink, once invoked, requires login with user name, password, and account credentials. QuickLink handles the logging in of the user to an appropriate account on the TransForm server, if needed, through its UI as well as the persistence across subsequent invocations of QuickLink of the login credentials obtained from the server using those credentials. Multiple tabs in a browser may be open at once, all running different QuickLink URLs to edit different form instances for the user/account combination.
Parameters for IFRAME use
The URL that is used to invoke QuickLink must include parameters (often called a Query component of the URL) after the domain and path, separated by a “?” character. The structure of the query follows a common Internet syntax. For example, the URL could be:
http://transform.alphasoftware.com/QuickLink?m=i&f=lflza6l9_br9pnc11
In this case, the “http://transform.alphasoftware.com/QuickLink” is the part that indicates the address on a particular server. We will call that the “QuickLink Web Address”. The part after the “?”, “m=i&f=lflza6l9_br9pnc11”, is the query. Multiple parameters in the query are separated by the “&” character. An initial “&” after the “?”is optional. (The construction of URLs with query strings this way is a normal, well-documented, web-development technology.)
The four QuickLink modes are specified by using the parameters in the query. The “m” parameter is used to explicitly specify the mode. Allowed values are: i, im, d, n, and q (representing Instance, Instance with Management Console role, Duplicate, New, and Queue). If the m parameter is missing, “i” is assumed. The other parameters are used to provide the details.
In addition to the parameters used by QuickLink when invoked using a link from, for example, an email, there are several additional parameters more applicable to IFRAME use. These additional parameters are used to control the area around the border of the app within its container, to control if and how to communicate with the window containing the IFRAME, and to control how to handle situations when the edited form instance is saved or the window closed.
Note: The values for the various parameters (the part after the “=”) should be encoded if they contain certain non-alphanumeric characters, such as using the JavaScript encodeURIComponent() function. For example, the value “calc(100% - 20px)” would be “calc(100%25%20-%2020px)”.
The additional parameters are:
- &windowmargin=margin attributes - For example: 10px auto 10px auto
- &windowmaxwidth=max width attribute - For example: 1024px or calc(100% - 20px)
- &windowboxshadow=box shadow attribute - For example: rgb(187, 187, 187) 0px 0px 10px
- &askonleave=Y/N (if Y or N, overrrides default) - Controls whether or not QuickLink will put up a warning message when the window is unloaded in certain cases (see JavaScript “window.onbeforeunload”).
- &onsave=stay - Leaves form instance displayed (with Save disabled since not dirty after a successful save). Otherwise, a “close” screen is displayed instead of the form.
- &closemsg=part of EDITFORM_PANEL message (URI-component encoded) - For example (the default in many cases): You may now close the browser tab. May be empty after the “=” to suppress that part of the message on the screen shown after saving.
- &postmessage=Y/N to parent window, default is N - Whether or not to post messages to the parent window. This is described in more detail below.
- &postmessageprefix=text - For example: ATeditForm, default is no prefix
Sample code for using an IFRAME with QuickLink
To use QuickLink in an IFRAME, you need to set the “src” attribute of the IFRAME to an appropriate URL, including parameters in the query string. Those parameters are usually determined dynamically and the src attribute set using JavaScript.
For example, the IFRAME element could be the following:
<iframe id="iframe" src=""style="width:100%;height:500px;border:1px solid #000;"></iframe>
JavaScript could be used to set the src attribute:
function loadsrc() {
var url = "https://transform.alphasoftware.com/QuickLink?m=im";
var instanceid = "abcdefgh_12345678";
url += "&f="+instanceid;
var iframe = document.getElementById("iframe");
iframe.src = url;
}Invoking the loadsrc() function would run QuickLink in the IFRAME with the form instance “abcdefgh_12345678” loaded.
To help demonstrate this functionality more fully, a simple sample HTML application will be used in this document.
When run in a browser, the sample HTML page looks like this:
The top part of the application has three text input controls to set some of the various parts of the QuickLink url. There is a “Load” button to load the IFRAME using a computed url. There are also two checkboxes to set some common parameters in the url and two placeholder for status messages set dynamically during execution. Below that is the IFRAME, shown with content already loaded into it in the screenshot.
The code for the sample application includes JavaScript to handle clicks on the button as well as for communication between the application and QuickLink in the IFRAME.
Here is the code:
<html>
<head>
<script>
function doload() {
var url = document.getElementById("url").value;
var instanceid = document.getElementById("instanceid").value;
var src = url+"?m=im&f="+instanceid;
if (document.getElementById("readonly").checked) {
src += "&ro";
}
if (document.getElementById("onsavestay").checked) {
src += "&onsave=stay";
}
var extra = document.getElementById("extra").value;
src += extra;
document.getElementById("message").innerHTML = "Loading...";
var iframe = document.getElementById("iframe");
iframe.src = src;
}
function loaded() {
document.getElementById("message").innerHTML = "";
}
function receivedmessage(event) {
var msg = event.data;
if (typeof msg != 'object') msg = {};
var ele = document.getElementById("iframe");
if (event.source!=ele.contentWindow) {
return;
}
switch (msg.cmd) {
case 'ATeditFormAfterSuccessfulSync':
alert("Save from QuickLink. Updated:"+
msg.updated+", Inserted:"+msg.inserted);
break;
case 'ATeditFormUpdateDirtyValue':
document.getElementById("modified").innerHTML =
msg.isDirty ? "Unsaved data" : "";
break;
default:
break;
}
}
window.addEventListener("message", receivedmessage, false);
</script>
</head>
<body>
<div style="padding:10px;">
URL:
<input id="url"
value="https://transform.alphasoftware.com/QuickLink.html"
style="width:400px;" />
<br><br>
Extra Parameters:
<input id="extra"
value="&postmessage=Y&postmessageprefix=ATeditForm" />
<br><br>
Form Instance ID:
<input id="instanceid" value="la22q6ip_n5ab4yhe"
style="width:400px;" />
<br><br>
<button onmouseup="doload();">Load</button>
<input type="checkbox" id="readonly" />
<label for="readonly">Read Only</label>
<input type="checkbox" id="onsavestay" />
<label for="onsavestay">On Save Stay</label>
<span id="message" style="font-style:italic;"></span>
<span id="modified" style="font-style:italic;"></span>
</div>
<div>
<iframe id="iframe" onload="loaded();" src=""
style="width:100%;height:500px;border:1px solid #000;"></iframe>
</div>
</body>
</html>How the sample code works
The doload() function at the beginning of the <script> section takes values from the input controls and assembles a url with the appropriate parameters. That url is then assigned to the src attribute of the IFRAME element at the end of the function. This initiates loading QuickLink into the IFRAME. The function also displays a message saying “Loading...”. Note: The parameter values typed into the Extra Parameters field should be appropriately encoded as described above.
The loaded() function is invoked when the IFRAME finishes loading. This removes the message.
The receivedmessage(event) function is invoked when a message is received from QuickLink running in the IFRAME. (The message is sent using a targetWindow.postmessage() method.) The function checks to ensure that the message is from the expected window. It then processes the data sent as part of the message, either displaying a message with information about a successful saving of edited form instance data or updating a message about whether or not there are unsaved edits. The data is an object with a “cmd” and other attributes. The different values for the cmd attribute are described below.
The <script> section also includes a statement to set the receivedmessage() function as the handler for the window “message” event.
The <body> section of the code includes <input> elements for the various values used to assemble the url. It also has a button to initiate loading the IFRAME as well as <span> elements to display the messages. Finally, it has the IFRAME element itself. The IRAME includes an “onload” attribute that invokes the loaded() function. QuickLink automatically resizes itself to fill its window. Here the IFRAME is set to have a width of 100% and a fixed height of 500px.
Messages from QuickLink
When &postmessage=Y, QuickLink will post messages to the IFRAME’s parent. Those messages will have a data value that is an object. The object will have a “cmd” attribute specifying the type of the message. The attribute value will start with the postmessageprefix value, if any, followed by one of the following values:
AfterSuccessfulSync
When QuickLink executes a successful Save operation (such as when the user clicks the Save button in the upper-left corner of the Form Details screen or a Change Status button in the form itself) and &postmessage=Y, the AfterSuccessfulSync command message is posted. In addition to the “cmd” attribute, there will be an “updated” and an “inserted” attribute, each with a numeric value. For edits, the “updated” attribute will be 1, and the “inserted” attribute will be 0.
UpdateDirtyValue
At various points while a user is using QuickLink to edit a form instance, if &postmessage=Y, the UpdateDirtyValue command message is posted. In addition to the “cmd” attribute, there will be an “isDirty” attribute with a Boolean value of either true or false. This value will correspond to whether or not the form instance (including form data and most meta data) has been changed. Unless hidden, the “Save” button in the upper-left corner of the QuickLink form instance details screen will have been enabled or disabled according to this value.